home *** CD-ROM | disk | FTP | other *** search
/ Utilities Professional 1-1500 / Utilities Professional 1-1500 (1994)(WPD)[!].iso / 12511500 / var1444.dms / var1444.adf / Docs / LIB.doc < prev    next >
Text File  |  1992-09-02  |  62KB  |  1,442 lines
  1. The C libraries provided with HCE are the original Sozobon-C libraries
  2. by Dale Schumacher, which were partially ported from the ATARI ST by 
  3. Jeff Lydiatt on the 17th june 1989 (ZC distribution). The only changes
  4. I have made to these libraries since, are bug fixes to 'stdio.lib',
  5. the addition of 'environment.c' to 'Misc.lib', and also changed 
  6. parts of the maths library for math routines from Detlef Wuerkner`s 
  7. 'HCC.lib' (HCC distribution).
  8.  
  9. Note about this document.
  10. -------------------------
  11. This document is based on the 'zc.lib.doc' by Jeff Lydiatt, which was based
  12. on the original 'dlibs.libs' document by Dale Schumacher for the ATARI ST.
  13. I have rewritten many parts, added some new stuff and also taken out 
  14. the parts which were only meant for the ATARI ST.
  15.  
  16. Note about error return values.
  17. -------------------------------
  18. On the ATARI ST functions return negative values on error.
  19. On the AMIGA functions may generate a positive value on error.
  20. If the global variable 'errno' contains a positve value, consider it to be
  21. an error returned from AmigaDos, via IoErr().
  22.  
  23. Note about 'Math.lib'.
  24. ----------------------
  25. The maths library uses the motorola fast floating point routines exclusively.
  26. The keyword 'float' acts the same as 'double'.
  27. The 'mathffp.library' and the 'mathtrans.library' are opened and closed
  28. each time you use one of there functions. If you open these libraries 
  29. yourself then you most also close them yourself.
  30.  
  31. Note about all libs.
  32. ---------------------
  33. The standard C libraries comprise of the following:
  34.  
  35.                               Maths.lib
  36.                               Misc.lib
  37.                               Stdio.lib
  38.                               String.lib
  39.  
  40. Normally all of the above files (except Maths.lib) would be joined to
  41. make a single C library. I have kept them seperate to try and make
  42. bug fixing and updating a bit easier.
  43.  
  44.  
  45.                         TABLE OF CONTENTS
  46.                       
  47.       Header files .................................. L64
  48.       Process control ............................... L151
  49.       Memory management ............................. L271
  50.       File handling ................................. L301
  51.       Input & Output ................................ L538
  52.       Formatting & Type conversion .................. L688
  53.       String manipulation ........................... L891
  54.       Charater functions ............................ L1102
  55.       Date & Time functions ......................... L1172
  56.       Searching & Sorting ........................... L1215
  57.       Error handling ................................ L1288
  58.       Variable argument lists ....................... L1310
  59.       Miscellaneous ................................. L1335
  60.       Revision record ............................... L1418
  61.       Final note .................................... L1427
  62.  
  63. **********************************************************************
  64. *                         HEADER FILES:                              *
  65. **********************************************************************
  66.  
  67. ar.h
  68.  This header defines the library archive header used by 'ar'.
  69.  
  70. assert.h
  71.  This header defines the assert() run-time condition checking macro.
  72.  
  73. basepage.h
  74.  The BASEPAGE struct and the _base variable, which is initialized
  75.  to point to the current process basepage, are defined in this file.
  76.  
  77. ctype.h
  78.  Character classification and conversion.
  79.  The isxxxx() macros and toxxxx() macros are defined in this file.
  80.  
  81. errno.h
  82.  This file defines the error code constants, the errno variable
  83.  and related error handling functions.
  84.  
  85. fcntl.h
  86.  This file defines the O_xxxx constants used by open().
  87.  
  88. limits.h
  89.  Various maximum and minimum values are defined by this file.
  90.  Among these are PATHSIZE and MAXINT.
  91.  
  92. macros.h
  93.  This file contains a few useful macros including min(), max(),
  94.  abs() and swap().
  95.  
  96. math.h
  97.  This file contains difines such as MAXDOUBLE and MAXFLOAT
  98.  and also contains function return values for all math functions.
  99.  
  100. setjmp.h
  101.  This file defines the buffer needed to save your context when
  102.  using setjmp()/longjmp() or catch()/throw().
  103.  
  104. stat.h
  105.  The struct stat and the file mode flag constants are defined
  106.  in this file.
  107.  
  108. stdarg.h
  109.  This header defines the type and macros needed for variable
  110.  argument list processing.
  111.  
  112. stddef.h
  113.  This is the root header file which should be included in all
  114.  programs.  It defines NULL, size_t, ptrdiff_t and the
  115.  offsetof() macro. (this file is included in stdio.h)
  116.  
  117. stdio.h
  118.  This header file should be present in nearly all C programs.
  119.  It defines the 'FILE' struct, EOF and contains extern
  120.  declarations for standard i/o (Stdio.lib) and other commonly 
  121.  used functions. For convenience, the constants TRUE, FALSE and 
  122.  ERROR are also defined in this file, although this is 
  123.  somewhat non-standard. Also this header file includes 
  124.  the <stddef.h> and the <stdlib.h> as these files are 
  125.  needed in most C programs anyway.
  126.  
  127. stdlib.h
  128.  Function prototypes and defines for Misc.lib.
  129.  This file defines the return values for the dynamic memory
  130.  managment functions, malloc(),calloc(),lalloc(),free() etc.
  131.  It also defines the return values for rand(),time(),mkdir() and
  132.  chk_abort().It also contains the defines for exit(), such as
  133.  EXIT_SUCCESS and EXIT_FAILURE.(this file is included by stdio.h)
  134.  
  135. string.h
  136.  This file defines aliases for string function names (since some
  137.  string functions have various names on different systems) and
  138.  extern declarations for all string functions.
  139.  
  140. time.h
  141.  This file defines time related constants and structures, and
  142.  extern declarations for the time functions.(Misc.lib)
  143.  
  144. types.h
  145.  Thie file contains typedefs for many special and/or non-standard
  146.  type names.  Many of the typedefs in this file define type names
  147.  which are ANSI and/or System V standard.  This file is included
  148.  by several other header files, and includes <stddef.h>.
  149.  
  150. ***********************************************************************
  151. *                  PROCESS CONTROL: (misc.lib)                        *
  152. ***********************************************************************
  153.  
  154.     You should include <stdlib.h> in your program if you use functions
  155.     from this section.(contains prototypes)
  156.  
  157. int _main()
  158.      This function defines the standard streams, checks to see which
  159.      of them are devices, and calls the user's main() function.
  160.      The startup module calls this function to start the C program. 
  161.      The following standard streams are initialized by _main():
  162.  
  163.      stdin   - Standard input, may be redirected
  164.      stdout  - Standard output, may be redirected
  165.      stderr  - Usually the system console
  166.  
  167.      The global variables '_argc', and  '_argv' are used to
  168.      store the values to be passed to the user's main().  If main()
  169.      returns then exit() is called with an EXIT_SUCCESS status.
  170.  
  171. int main(int argc, char *argv[])
  172.      This function is not actually in the standard libraries, 
  173.      but must be present somewhere in the user's code. 
  174.      The parameters passed to it by '_main()' are the number of 
  175.      arguments in the command line and a pointer to the arguments.
  176.      The return value from 'main()' is passed, by '_main()', to 'exit()'. 
  177.      Therefore, you should always 'return()' from 'main()', or call 
  178.      'exit()' directly.
  179.  
  180. void exit(int status)
  181.      Flushes and closes all open streams.
  182.      Returns <status> to the computers operating system.
  183.  
  184. void abort()
  185.      Prints the message "^C" to stderr and calls exit() with a 
  186.      status code of 3.
  187.  
  188. char *getenv(char *v)
  189.      Search for environment variable *v.  
  190.      If *v is found, a pointer to the string contained in the env variable
  191.      is returned. A NULL return value indicates, not found.
  192.  
  193. int setenv(char *v, *s)
  194.     Sets environment variable *v to string *s.
  195.     Returns success/failure indicator.(0=failure,1=success)
  196.     note: To embed a space in a file name, precede it with 
  197.           the escape delimiter.(usually a backslash).
  198.           This applies to all env functions.
  199.  
  200. int putenv(char *s)
  201.     The form is:
  202.                  
  203.     <VARIABLE>=<value>
  204.  
  205.     Set an envirenment varible to <value>.
  206.     Returns success/failure indicator.(0=failure,1=success)
  207.  
  208. char *ParseEnv(char *s)
  209.     ParseEnv(), holds a global string called 'String' which is 
  210.     initialized to *s. This env 'String' is searched for the first env
  211.     entry and if found a pointer to the entry is returned.
  212.     If ParseEnv() is called with a NULL value then the last env
  213.     'String' to be passed is searched for the next env entry.
  214.     A NULL return value indicates, no more entries.
  215.  
  216. LONG System0(char *name,BPTR seglist,char *args)
  217.     Does CLI/Shell commands from within an application.
  218.  
  219.     <name>    is the name of the command file to be run.
  220.     <seglist> must point to a file previously loaded into memory with
  221.               'BPTR LoadSeg(char *name)' or the like.
  222.     <args>    a list of args to be past to the command seperated by spaces.
  223.  
  224.     Return values:
  225.                   1) Returns the commands 'exit()' status if command was run.
  226.                   2) Returns -1 if 'System0()' was called from workbench,
  227.                      (must only call from a CLI/Shell process).
  228.                   3) Returns -2 if memory failure.
  229.  
  230. long fexecv(char *cmd,char *argv[])
  231.     Does CLI/Shell commands from within an application.
  232.     Simplifies a call to 'System0()'.
  233.  
  234.     <cmd>    is the name of the command file to be run.
  235.     <argv>   an array of arguments to be passed to the command.
  236.  
  237.     Return values:
  238.                   1) Returns the commands 'exit()' status if command was run.
  239.                   2) Returns -1 if 'fexecv()' was called from workbench,
  240.                      (must only call from a CLI/Shell process).
  241.                   3) Returns -1 if the command file wasn't found.
  242.                   4) Returns -2 if memory failure.
  243.  
  244. int setjmp(jmp_buf context)
  245.     Save <context> for longjmp(). You MUST include <setjmp.h> to use.
  246.     Calling this function saves the current program context in the
  247.     context buffer provided and returns zero.  A later call to the
  248.     longjmp() function will cause the context to be restored and
  249.     your program will continue as if it just returned from setjmp(),
  250.     but this time with the (non-zero) return value specified in the
  251.     longjmp() call.  THE SAVED CONTEXT WILL NOT BE VALID IF YOU
  252.     EXIT THE FUNCTION THAT CALLED setjmp().
  253.  
  254. void longjmp(jmp_buf context, int rv)
  255.     Return <rv> to the <context> saved by setjmp(). (see also, setjmp)
  256.     You MUST include <setjmp.h> to use.
  257.  
  258. int catch(jmp_buf context, int (*func)())
  259.     Execute <func> with <context> saved for throw().  You MUST include
  260.     <setjmp.h> to use.  Return the value returned by <func>.  The main
  261.     advantage of these functions over catch/throw is the ability to
  262.     return zero from the function executed, and the logically "cleaner"
  263.     encapsulation of the non-local jump operation. These functions
  264.     are patterned after similar functions in LISP. (see also, setjmp/longjmp)
  265.  
  266. void throw(jump_buf context, int rv)
  267.     Return <rv> to <context> saved by catch().  You MUST include
  268.     <setjmp.h> to use.
  269.  
  270. ***********************************************************************
  271. *                    MEMORY MANAGEMENT: (misc.lib)                    *
  272. ***********************************************************************
  273.  
  274.     You should include <stdlib.h> in your program if you use functions
  275.     from this section.(prototypes for malloc,calloc etc)
  276.  
  277. char *malloc(int size)
  278.     Allocate at least <size> bytes of memory.  A pointer to the
  279.     requested block is returned, or NULL if there was not enough
  280.     free memory available.
  281.  
  282. char *calloc(int n, size_t size)
  283.     Allocate space for an array of <n> element of <size> bytes each.
  284.     If the storage can be allocated, it is initialized to all zero.
  285.     NULL is returned if there isn't enough free memory.
  286.  
  287. char *lalloc(long size)
  288.     Allocate at least <size> bytes of memory.  A pointer to the
  289.     requested block is returned, or NULL if there is not enough
  290.     free memory available.
  291.  
  292. void free(char *addr)
  293.     Release the memory block at <addr> back into the free memory pool.
  294.  
  295. long msize(long *addr)
  296.     Return the size, in bytes, of the memory block at <addr>.  Note
  297.     that the size is a long value, since the block may have been
  298.     allocated by lalloc().
  299.  
  300. *************************************************************************
  301. *                 FILE HANDLING: (stdio.lib/misc.lib)                   *
  302. *************************************************************************
  303.  
  304.     You should include <stdio.h> in your program if you use functions
  305.     from this section.(contains prototypes,defines and macros)
  306.  
  307. int chdir(char *pathname)
  308.     Changes the current working directory to <pathname>.
  309.     Returns 0 for success, or a positive error code.
  310.  
  311. int mkdir(char *pathname)
  312.     Creates a new directory called <pathname>.
  313.     Returns 0 for success, or a positive error code.
  314.  
  315. int rmdir(char *pathname)
  316.     Removes an existing directory called <pathname>.
  317.     Returns 0 for success, or a positive error code.
  318.  
  319. int access(char *name, int access_mode)
  320.     Return 0 if a file with the given <name> can be accessed
  321.     in the given <access_mode>.  Possible <access_mode> values are:
  322.         0 - file exists.
  323.         2 - file can be written.
  324.         4 - file can be read.
  325.         6 - file can be read and written.
  326.     Returns -1 if file not found.
  327.  
  328. int fexists(fname)
  329.     call access() above with fname and 0 mode.(macro)
  330.  
  331. int exists(fname)
  332.     exactly the same as fexists() above.(macro)
  333.  
  334. char *_splitpath(char *src, *drive, *path, *file, *ext)
  335.  Parse the <src> filename into component parts. Returns <src>.
  336.  If any of the component pointers is NULL, that component will
  337.  be parsed, but not saved.  If a given component does not exist
  338.  in the <src> string, the component will be empty, (ie.: "").
  339.  The <drive> component will be a drive name followed by a colon,
  340.  (ie: "df0:").  The <path> component will be the subdirectory names
  341.  leading up to the filename, but will not include a trailing '/'
  342.  unless the path is simply the root path "/", and there will only
  343.  be a leading '/' if the path is fully qualified, or "rooted", 
  344.  ie: "/this/is/a/path/name".  The <file> component is the base filename
  345.  without any extension, ie: "filename".  The <ext> component is
  346.  the file extention with no leading '.', ie: "txt".  Recommended
  347.  sizes for the components is Drive[4], Path[128], File[10], Ext[4].
  348.  (This func lives in 'string.lib').
  349.  
  350. char *_makepath(char *dst, *drive, *path, *file, *ext)
  351.  Build the <dst> filename from component parts. Returns <dst>.
  352.  This function is basically in inverse of _splitpath(), and will
  353.  accept the components parsed by _splitpath() as input.  It will
  354.  also allow a little more flexibility in that it will treat any
  355.  component which is a NULL pointer as an empty field, and the
  356.  <path> component may optionally have a trailing '/'.
  357.  (This func lives in 'string.lib').
  358.  
  359. int stat(char *name, struct stat *statbuf)
  360.  Search for file <name> and load <statbuf> with information
  361.  about the file if it is found.  Return 0 if found, or
  362.  ERROR (-1) if no file/directory matched <name>.  Volume
  363.  labels are not included in the search.  The file <stat.h>
  364.  must be included if you use this function, since it defines
  365.  the stat structure.
  366.  
  367. long fsize(char *name)
  368.  Return the size of the file <name> in bytes.  Note that this
  369.  is a long value.  Return -1L if the file is not found.
  370.  
  371. int isatty(int handle)
  372.  Return non-zero if <handle> refers to a character device.
  373.  Negative handles always refer to character devices.
  374.  
  375. int creat(char *filename, int pmode)
  376.  Create a new file with the given <filename>.  If a file with
  377.  the name already exists, it will be truncated to zero bytes.
  378.  <pmode> specifies the attributes initially given to the file.
  379.   Valid <pmode> values are:
  380.                     0x00      normal, read/write
  381.                     S_ISRO    read only
  382.                     S_IFHID   hidden file
  383.                     S_IFSYS   system file
  384.                     S_ISVOL   volume label
  385.  If S_ISVOL mode is specified, it must be the only mode given.
  386.  Other modes may be combined with the '|' operator.  The <stat.h>
  387.  file contains information useful with this function.
  388.  
  389. int open(char *filename, int [iomode, pmode])
  390.   Attempt to open <filename> with the given <iomode>.  A file handle
  391.   is returned if the open succeeds.  A negative error code is returned
  392.   for errors.  Valid <iomode> values are:
  393.          O_RDONLY  read mode
  394.          O_WRONLY  write mode
  395.          O_RDWR    read/write mode
  396.   In addition to the (mutually exclusive) modes above, one or more
  397.   of the following options may be '|'-ed with <iomode>:
  398.          O_APPEND start file pointer at end of file
  399.          O_TRUNC  if file exists, truncate to 0 length
  400.          O_CREAT  creat() file if none exists (uses <pmode>)
  401.          O_EXCL   return EEXIST if file exists and
  402.                   O_CREAT is specified (exclusive mode).
  403.  Error returns are always < -3.  The <fcntl.h> file
  404.  contains iomode constants.  The <stat.h> file contains pmode
  405.  constants.
  406.  
  407. int close(int h)
  408.  Close file referenced by the file handle <h>.  Return 0 for
  409.  success, or a negative error code.
  410.  
  411. int remove(char *filename)
  412.  Delete <filename>, if it exists.  Return 0 for success, or a
  413.  negative error code.
  414.  
  415. int rename(char *oldname, *newname)
  416.  Change the name of file <oldname> to <newname>.  You may use this
  417.  function to move files from one directory (pathname) to another,
  418.  but not from one drive to another.  Return 0 for success, or a
  419.  negative error code.
  420.  
  421. long lseek(int h, long offset, int origin)
  422.  Move file pointer for file <h> to specified location.  <origin>
  423.  specifies the starting point for the <offset> distance.  Valid
  424.  <origin> values are:
  425.           SEEK_SET   from beginning of file (0)
  426.           SEEK_CUR   from current location (1)
  427.           SEEK_END   from end of file (2)
  428.  The <offset> value is the distance in bytes from the origin.
  429.  The final file position, or a negative error code, is returned.
  430.  
  431. long tell(int h)
  432.  Return the current file position for the file <h>.
  433.  
  434. FILE *fopen(char *filename, char *mode)
  435.  Open <filename> as a stream file.  This is the normal open way
  436.  to open a file.  The <mode> is a string specifying the mode(s)
  437.  that are relevent to the file open.  Valid <mode> characters are:
  438.          "r"   read mode
  439.          "w"   write mode
  440.          "a"   append mode
  441.          "b"   binary mode
  442.          "t"   text (translated) mode
  443.  At least one of "r", "w" or "a" must be specified.  "t" is assumed
  444.  and indicates that <nl> is translated to <cr><lf> on output and
  445.  vica-versa on input.  If the stream is a character device, the
  446.  translation is slightly different.  The output translation is the
  447.  same, but on input <cr> and <lf> both become <nl> in all cases.
  448.  The "b", for binary mode, overides "t" and indicated that characters
  449.  are not translated during i/o operations.  "a" represents append
  450.  mode and means that the file pointer will initially be placed at
  451.  the end of the file.  "w" mode will create a file if it doesn't
  452.  exist, or zero an existing file.  If "r" is the only mode specified,
  453.  the file must already exist.  A (FILE *) pointer is returned if the 
  454.  open succeeds, or NULL if it fails.
  455.  
  456. FILE *freopen(char *filename, char *mode, FILE *fp)
  457.  Closes the file associated with <fp> and opens the new file as with
  458.  fopen(), except that a new FILE structure is not created.  The
  459.  existing FILE structure pointed to by <fp> is re-initialized with
  460.  the new file information.  This is typically used to redirect i/o
  461.  to standard streams stdin, stdout, stderr.  <fp> is returned for success, 
  462.  or NULL for failure.
  463.  
  464. FILE *fdopen(int h, char *mode)
  465.  Associates a stream with the already open file <h>.  The <mode>
  466.  values are the same as for fopen(), but MUST be compatible with
  467.  the mode in which <h> was open()ed.  This function allows a file
  468.  opened with the low level open()/creat() calls to be used as a
  469.  buffered/translated stream.  A pointer to a FILE struct is returned,
  470.  or NULL for errors.
  471.  
  472. int fclose(FILE *fp)
  473.  Close the stream <fp>, flushing the buffer.  Returns 0 on success.
  474.  
  475. void setbuf(FILE *fp, char *buf)
  476.  If <buf> is NULL, make <fp> unbuffered; else <buf> must point to a 
  477.  buffer of BUFSIZ characters to be used as the stream buffer for <fp>.
  478.  
  479. void setvbuf(FILE *fp, char *buf, int bmode, int size)
  480.  If <buf> is NULL or <bmode> is _IONBF, make <fp> unbuffered;
  481.    otherwise <buf> points to a buffer of <size> characters to be
  482.    used as the stream buffer for <fp>.  The <bmode> variable
  483.    indicates the type of buffering desired, as follows:
  484.   _IONBF  No buffering
  485.   _IOFBF  Full buffering (normal)
  486.   _IOLBF  Line buffering (not supported, same as _IOFBF)
  487.  
  488. int fseek(FILE *fp, long offset, int origin)
  489.  Operates like lseek(), except it works on streams.  Note that
  490.  stream file positions may be misleading due to translation of
  491.  <nl> characters during i/o.  ftell() may be used reliably with
  492.  fseek() to reposition a file to a prior location.  WARNING:
  493.  fseek() returns 0 for success, none-zero for failure, according
  494.  to the ANSI standard.  Some implementations use 0 for failure.
  495.  This function is maintained for compatibility with old programs.
  496.  fsetpos() should be used in new code.  (see: fsetpos)
  497.  
  498. void rewind(FILE *fp)
  499.  Operates like fseek(fp, 0L, SEEK_SET), except it also clears the
  500.  end-of-file and error flags for <fp>.  There is no return value.
  501.  
  502. long ftell(FILE *fp)
  503.  Operates like tell(), except it works on streams.  Note that
  504.  stream file positions may be misleading due to translation of
  505.  <nl> characters during i/o.  This function is maintained for
  506.  compatibility with old programs.  fsetpos() should be used in
  507.  new code.  (see: fsetpos)
  508.  
  509. int fgetpos(FILE *fp, fpos_t *pos)
  510.  Get the position of the stream <fp> and store it at the location
  511.  pointed to by <pos>.  This is the new X3J11 function to replace
  512.  ftell().  Returns 0 for success and ERROR for failure.
  513.  
  514. int fsetpos(FILE *fp, fpos_t *pos)
  515.  Set the position of the stream <fp> to the value stored at the
  516.  location pointed to be <pos>.  Note that this function is only
  517.  required to work properly for a <pos> value which was previously
  518.  obtained by fgetpos() on the same stream.  This is the new X3J11
  519.  function to replace fseek().  Returns 0 for success and ERROR for
  520.  failure.
  521.  
  522. int fileno(FILE *fp)
  523.  Return the file handle associated with the stream <fp>.(macro)
  524.  
  525. int feof(FILE *fp)
  526.  Return non-zero if <fp> is at end of file.(macro)
  527.  
  528. int ferror(FILE *fp)
  529.  Return non-zero if and error has occurred on <fp>.(macro)
  530.  
  531. void clearerr(FILE *fp)
  532.  Clear the error flag on <fp>.(macro)
  533.  
  534. sync()
  535.  Provided for compatibility. (dummy macro)
  536.  
  537. ***********************************************************************
  538. *               INPUT & OUTPUT FUNCTIONS: (stdio.lib)                 *
  539. ***********************************************************************
  540.  
  541.  You should include <stdio.h> in your program if you use functions
  542.  from this section.(prototypes/defines/macros)
  543.  
  544. int read(int h, char *data, int length)
  545.  Read <length> bytes from the file reference by file handle <h>.
  546.  Data is stored in the buffer pointed to by <data>.  The number
  547.  of bytes actually read is returned, 0 for end of file, or a
  548.  negative error code.  Note that the maximum number of bytes
  549.  that can be read by this function is MAXINT.
  550.  
  551. int write(int h, char *data, int length)
  552.  Write <length> bytes to the file reference by file handle <h>.
  553.  Data is written from the buffer pointed to by <data>.  The number
  554.  of bytes actually written is returned, or a negative error code.
  555.  Note that the maximum number of bytes that can be written by
  556.  this function is MAXINT.
  557.  
  558. int fread(char *data, int size, int count, FILE *fp)
  559.  Read <count> items of <size> characters each from stream <fp>.
  560.  Data is stored in the buffer pointed to by <data>.  The number of
  561.  full items actually read is returned, or a negative error code.
  562.  This call DOES NOT translate characters, even if the stream is
  563.  opened in translate mode.
  564.  
  565. int fwrite(char *data, int size, int count, FILE *fp)
  566.  Write <count> items of <size> characters each to stream <fp>.
  567.  Data is read from the buffer pointed to by <data>.  The number of
  568.  full items actually written is returned, or a negative error code.
  569.  This call DOES NOT translate characters, even if the stream is
  570.  opened in translate mode.
  571.  
  572. int fgetc(FILE *fp)
  573.  Get a character from <fp>.  Returns the character or EOF.
  574.  
  575. int fungetc(char c, FILE *fp)
  576.  Push the character <c> back to be gotten by the next fgetc()
  577.  call on <fp>.  Only 1 character may be ungotten at a time on
  578.  each stream.  Subsequent calls to fungetc() will write over
  579.  the currently saved character.
  580.  
  581. int fputc(char c, FILE *fp)
  582.  Put the character <c> to the stream <fp>.
  583.  
  584. int fflush(FILE *fp)
  585.  Flush the file i/o buffer of the stream <fp>.  The buffer is
  586.  automatically flushed when it is full, the stream is closed,
  587.  or the program terminates through exit().  This function has
  588.  no effect if the stream in unbuffered.  Call this function
  589.  before switching between reading and writing on a stream which
  590.  is opened for both.
  591.  
  592. int getc(FILE *fp)
  593.  Same as fgetc() but implemented as a macro.
  594.  
  595. int ungetc(char c, FILE *fp)
  596.  Same as fungetc() but implemented as a macro.
  597.  
  598. int putc(char c, FILE *fp)
  599.  Same as fputc() but implemented as a macro.
  600.  
  601. int getw(FILE *fp)
  602.  Get a 2-byte value from the stream <fp>.  The high-order byte is
  603.  read first.  Use feof() to test for end-of-file.(see: feof)
  604.  
  605. int putw(int n, FILE *fp)
  606.  Put the 2-byte value <n> to the stream <fp>.  The high-order byte
  607.  is written first.
  608.  
  609. int getl(FILE *fp)
  610.  Get a 4-byte value from the stream <fp>.  The high-order byte is
  611.  read first.  Use feof() to test for end-of-file.(see: feof)
  612.  
  613. int putl(long n, FILE *fp)
  614.  Put the 4-byte value <n> to the stream <fp>.  The high-order byte
  615.  is written first.
  616.  
  617. int getchar()
  618.  Same as "fgetc(stdin)".(macro)
  619.  
  620. int ungetchar(char c)
  621.  Same as "fungetc(c, stdin)".  Note that this name will conflict
  622.  with any function beginning "ungetch..." due to having only 7
  623.  significant characters in external identifiers.(macro)
  624.  
  625. int putchar(char c)
  626.  Same as "fputc(c, stdin)".(macro)
  627.  
  628. char *fgets(char *data, int limit, FILE *fp)
  629.  Get data from <fp> and put it in the <data> buffer.  At most,
  630.  <limit>-1 characters will be read.  Input will also be terminated
  631.  when a newline is read.  <data> will be '\0' terminated and the
  632.  newline, if read, will be included.  A pointer to the start of
  633.  <data> is returned, or NULL for EOF.
  634.  
  635. void fputs(char *data, FILE *fp)
  636.  Write the characters in <data> to the stream <fp>.  A newline
  637.  WILL NOT be added.
  638.  
  639. char *gets(char *data)
  640.  Get data from stdin and put it in the <data> buffer.  Input is
  641.  terminated when a newline is read.  The newline will be replaced
  642.  by a '\0' to terminate the string.  A backspace character will
  643.  remove the preceeding character from the buffer, but will not
  644.  backspace past the start of the buffer.  A pointer to the start
  645.  of <data> is returned, or NULL for EOF.
  646.  
  647. void puts(char *data)
  648.  Write the characters in <data> to stdout.  A newline WILL be
  649.  written after the data.
  650.  
  651. long fprintf(FILE *fp, char *fmt[, arg1, ..., argN])
  652.  Formatted output to the stream <fp>.  See the _printf() function
  653.  for a description of the <fmt> formatting string.
  654.  
  655. long printf(char *fmt[, arg1, ..., argN])
  656.  Formatted output to the stdout stream.  See the _printf() function
  657.  for a description of the <fmt> formatting string.
  658.  
  659. int sprintf(char *buf, *fmt[, arg1, ..., argN])
  660.  Formatted output to the string <buf>.  See the _printf() function
  661.  for a description of the <fmt> formatting string.
  662.  
  663. long vfprintf(FILE *fp, char *fmt, va_list ap)
  664.  Formatted output to the stream <fp> with a variable argument list.
  665.  See _printf() for formatting and va_start() for stdarg explanation.
  666.  
  667. long vprintf(char *fmt, va_list ap)
  668.  Formatted output to the stdout stream with a variable argument list.
  669.  See _printf() for formatting and va_start() for stdarg explanation.
  670.  
  671. int vsprintf(char *buf, char *fmt, va_list ap)
  672.  Formatted output to the string <buf> with a variable argument list.
  673.  See _printf() for formatting and va_start() for stdarg explanation.
  674.  
  675. long fscanf(FILE *fp, char *fmt[, arg1, ..., argN])
  676.  Formatted input from the stream <fp>.  See the _scanf() function
  677.  for a description of the <fmt> formatting string.
  678.  
  679. long scanf(char *fmt[, arg1, ..., argN])
  680.  Formatted input from the stdin stream.  See the _scanf() function
  681.  for a description of the <fmt> formatting string.
  682.  
  683. long sscanf(char *buf, *fmt[, arg1, ..., argN])
  684.  Formatted input from the string <buf>.  See the _scanf() function
  685.  for a description of the <fmt> formatting string.
  686.  
  687. ***********************************************************************
  688. *         FORMATTING & TYPE CONVERSION: (stdio.lib/string.lib)        *
  689. ***********************************************************************
  690.  
  691.  You should include either <stdio.h> or <string.h> in your program
  692.  if you use functions from this section, (prototypes/defines/macros).
  693.  I have placed a comment at the end of each function description to
  694.  explain which include is needed.
  695.  
  696. int _printf(char *op, int (*put)(), char *fmt, int *args)
  697.  This function does all the work for printf(), etc.  Many systems
  698.  don't provide direct access to this function (or it's equivalent),
  699.  but it is useful for writing your own printf()-like functions.
  700.  Since this is a non-standard interface, and v[sf]print() is now
  701.  available, you should probably use the stdarg functions instead.
  702.  <fmt> points to a format control string.  <args> points to a
  703.  list of arguments.  The format string is used to create and output
  704.  a stream with arguments.  The <put> function is used to output
  705.  each character.  The <op> parameter is given to the <put> function
  706.  to specify the output stream.  Calls to <put> are of the form:
  707.  "(*put)(c, op);" where <c> is the character to output.  The format
  708.  string is composed of characters and format specifications.  The
  709.  '%' character introduces a format specifier.  The general form of
  710.  a format specifier is:
  711.  
  712.    %[-][ |+][0][<width>|*][.[<precision>|*]][l]{d|i|u|o|x|p|b|c|s}
  713.  
  714.  The '-' specifies left justification.  The ' ' or '+' specifies
  715.  the character which preceeds positive numeric values.  The '0'
  716.  specifies that numeric fields will be padded with '0' rather than
  717.  ' '.  The <width> field is a numeric value specifying a minimum
  718.  field width.  The <precision> field is a numeric value specifying
  719.  the maximum number of data characters to display.  If '*' is
  720.  specified for the width or the precision, an "int" value is taken
  721.  from the argument list and used for that value.  If no width is
  722.  specified, the field width varies according to the data width.  If
  723.  no precision is specified, all data characters are included in the
  724.  data width.  If the data width exceeds the field width, the field
  725.  width will expand to allow all data characters to be printed.
  726.  Including the 'l' or capitalizing the trailing character specifies
  727.  that the associated value is a "long" type.  The trailing character
  728.  specifies the format type, as follows:
  729.        d Signed decimal integer
  730.        i same as 'd'
  731.        u Unsigned decimal integer
  732.        o Unsigned octal integer
  733.        x Unsigned hexadecimal integer
  734.        b Unsigned binary integer
  735.        p Pointer (displayed in %06.8lX format)
  736.        c Character
  737.        s String
  738.  If the character following the '%' is not recognized, it is
  739.  simply passed along to the output stream, thus "%%" is used to
  740.  print a single '%' character. (include: <stdio.h>)
  741.  
  742. char *ltoa(long n, char *buf, int radix)
  743.  Convert the long value <n> to a string in <buf> using <radix>
  744.  as the number base.  If <n> is negative, then '-' will be the first
  745.  character in <buf>.  A pointer to <buf> is returned.
  746.  (include: <string.h>)
  747.  
  748. char *ultoa(unsigned long n, char *buf, int radix)
  749.  Convert the unsigned long value <n> to a string in <buf> using
  750.  <radix> as the number base.  A pointer to <buf> is returned.
  751.  (include: <string.h>)
  752.  
  753. char *itoa(int n, char *buf, int radix)
  754.  Convert the integer value <n> to a string in <buf> using <radix>
  755.  as the number base.  If <n> is negative, '-' will be the first
  756.  character in <buf>.  A pointer to <buf> is returned.
  757.  (include: <string.h>)
  758.  
  759. long atol(char *number)
  760.  Convert the string <number> to a long value.  Leading whitespace
  761.  is ignored, a leading +/- is optional.  Characters are processed
  762.  until a non-digit is reached.  Return value is undefined in an
  763.  overflow situation. (include: <string.h>)
  764.  
  765. int atoi(char *number)
  766.  Convert the string <number> to an int value.  Leading whitespace
  767.  is ignored, a leading +/- is optional.  Characters are processed
  768.  until a non-digit is reached.  Return value is undefined in an
  769.  overflow situation. (include: <string.h>)
  770.  
  771. long strtol(char *number, char **nptr, int base) 
  772.  Convert the string <number> to a long value of base <base>.  Bases
  773.  from 0 to 36 are allowed.  Leading whitespace is ignored, and a
  774.  leading +/- is optional.  If the <base> is 0, a leading '0'
  775.  indicates base 8 and a leading "0x" or "0X" indicates base 16.
  776.  Characters are processed until a character is found which is not in
  777.  the specified base.  If <nptr> is non-NULL, it will be set to point
  778.  to the character which terminated the translation in <number>.
  779.  Return value is undefined in an overflow situation.
  780.  (include: <string.h>)
  781.  
  782. unsigned long strtoul(char *number, char **nptr, int base)
  783.  Convert the string <number> to an unsigned long value of base
  784.  <base>.  Bases from 0 to 36 are allowed.  Leading whitespace is
  785.  ignored.  If the <base> is 0, a leading '0' indicates base 8 and a
  786.  leading "0x" or "0X" indicates base 16.  Characters are processed
  787.  until a character is found which is not in the specified base.  If
  788.  <nptr> is non-NULL, it will be set to point to the character which
  789.  terminated the translation in <number>.  Return value is undefined
  790.  in an overflow situation. (include: <string.h>)
  791.  
  792. int _scanf(char *ip, int (*get)(), int (*unget)(), char *fmt, char **args)
  793.  This function does all the work for scanf(), etc.  Many systems
  794.  don't provide direct access to this function (or it's equivalent),
  795.  but it is useful for writing your own scanf()-like functions.
  796.  <fmt> points to a format control string.  <args> points to a
  797.  list of arguments, each of which is the address of a variable in
  798.  which input data may be stored.  The format string is used to
  799.  control reading of characters from the <get> function.  As each
  800.  character is needed <get> is called in the form "c = (*get)(ip);"
  801.  where <c> is the character read (negative for errors) and <ip> is
  802.  the auxiliary pointer specified by the <ip> parameter.  If a
  803.  character needs to be un-gotten, a call to <unget> of the form
  804.  "(*unget)(c, ip);" is made.  The format string is composed of
  805.  characters and format specifications.  Any characters in <fmt>,
  806.  except whitespace characters, which are not part of a format
  807.  specifier are expected to be matched one-to-one by characters in
  808.  the input stream.  Scanning terminates if a mismatch occurs or if
  809.  any call to <get> results in an error.  Whitespace characters
  810.  match 0 or more whitespace characters in the input stream.  The
  811.  '%' character introduces a format specifier.  The general form of
  812.  a format specifier is:
  813.  
  814.                 %[*][<width>][l|h]{d|u|o|x|b|i|c|s}
  815.  
  816.  The '*' specifies that a field is to be scanned but not stored.
  817.  No variable pointer should be provided for non-stored format
  818.  specs.  The <width> field specifies the maximum number of
  819.  characters to be processed to fill the given format type.  Less
  820.  than <width> characters will be processed if the field ends
  821.  before <width> characters have been processed.  A field ends when
  822.  either a whitespace character, or a character which does not fit
  823.  the specified format, is read.  The preceding 'l' (or
  824.  capitalizing the conversion character) specifies that the
  825.  associated variable is a "long" type.  The trailing character
  826.  specifies the format type, as follows:
  827.         d Signed decimal integer
  828.         u Unsigned decimal integer
  829.         o Unsigned octal integer
  830.         x Unsigned hexadecimal integer
  831.         b Unsigned binary integer
  832.         i Unsigned decimal/octal/hexadecimal/binary integer
  833.         c Character
  834.         s String
  835.  If a <width> is specified with the 'c' format, exactly <width>
  836.  characters (including whitespace) are read from the input stream,
  837.  and written to a string.  No '\0' character is added If the
  838.  character following the '%' is not recognized, it is expected to
  839.  match the input stream as a non-format character, thus "%%" is
  840.  used to match a single '%' character.
  841.  One additional conversion is the brace-format.  Shown as "%[...]",
  842.  the '...' represent a list of characters.  If the first character
  843.  in the list is a '^', the field contains any characters -not- in
  844.  the list (starting with the 1st character after the '^').  If the
  845.  first character of the list is not a '^', then the field will
  846.  only contain those characters found in the list.  A right brace 
  847.  character (']') can be included as one of the list of characters
  848.  by placing it as the first character in the list.  If the '^'
  849.  negation character is the first character, the included brace
  850.  should be the next character after the '^'.  For maximum
  851.  portability, a range should be explicitly given (a good example
  852.  would be "%[0123456789]"), but to allow for porting from
  853.  systems with smarter scanf functions, this version of scanf
  854.  also supports ranges represented using a <first>-<last>
  855.  form (eg: "%[0-9]").  To use the first-last form, the
  856.  character <first> must be lexically less than or equal to
  857.  the character <last>.  If this rule is violated, or if the
  858.  hyphen is the first or last character of the list, the
  859.  hyphen will be assumed to be just another character in the
  860.  list and no range expansion will be done.  The resulting
  861.  string containing the characters in (or not in) the list
  862.  will be null terminated.  It should be noted that, unlike
  863.  most of the other formats, this conversion does allow the
  864.  programmer to specify that whitespace characters will be
  865.  included in the resulting string. (include: <stdio.h>)
  866.  
  867. char *ctlcnv(char *string)
  868.  Convert \<char> notation in <string> to actual characters.  This
  869.  is useful for reading strings from a stream when you want to allow
  870.  insertion of control character or other characters that may have
  871.  special meaning otherwise, or may not otherwise be allowed.  The
  872.  following formats are supported:
  873.   \n  newline or linefeed
  874.   \r  carriage return
  875.   \0  null character (value 0)
  876.   \b  backspace
  877.   \t  horizontal tab
  878.   \v  vertical tab
  879.   \f  form feed
  880.   \a  alarm (bell)
  881.   \\  backslash
  882.   \'  single quote
  883.   \"  double quote
  884.   \NNN  octal constant
  885.   \xNN  hexadecimal constant
  886.   \<nl>  "folded" line (both characters removed)
  887.  A pointer to the modified <string> is returned.
  888.  (include: <string.h>)
  889.  
  890. ***********************************************************************
  891. *                  STRING MANIPULATION: (string.lib)                  *
  892. ***********************************************************************
  893.  
  894.  You should include <string.h> in your program if you use functions
  895.  from this section.(prototypes)
  896.  
  897. char *memmove(char *dest, char *source, int len)
  898.  Copies the <source> block to the <dest>.  <len> bytes are
  899.  always copied.  No terminator is added to <dest>.  A pointer
  900.  to <dest> is returned.  Overlap checking IS done.
  901.  
  902. char *lmemmove(char *dest, char *source, long len)
  903.  Same as memmove() except a long value is used for <len>.
  904.  
  905. char *memcpy(char *dest, char *source, int len)
  906.  Copies the <source> block to the <dest>.  <len> bytes are
  907.  always copied.  No terminator is added to <dest>.  A pointer
  908.  to <dest> is returned.  Overlap checking IS NOT done.
  909.  
  910. char *lmemcpy(char *dest, char *source, long len)
  911.  Same as memcpy() except a long value is used for <len>.
  912.  
  913. char *memset(char *dest, char data, int len)
  914.         Set <len> bytes of <dest> to <data>. 
  915.         A pointer to <dest> is returned.
  916.  
  917. int memcmp(char *blk1, char *blk2, int len)
  918.  Lexicographically compare the two blocks.  Return a value
  919.  indicating the relationship between the blocks.  Possible
  920.  return values are:
  921.                       negative  = blk1 < blk2
  922.                       0         = blk1 == blk2
  923.                       positive  = blk1 > blk2
  924.  <len> bytes are always compared.
  925.  
  926. int memicmp(char *blk1, char *blk2, int len)
  927.  Compare blocks as with memcmp(), but ignore the case of any
  928.  alphabetic characters.
  929.  
  930. char *memccpy(char *dst, char *src, char c, int cnt)
  931.  Copy bytes from <src> to <dst> until either <cnt> bytes have been
  932.  copied, or the character <c> has been copied.  If <c> is found,
  933.  a pointer to the character following <c> in <dst> is returned, or
  934.  NULL is <cnt> reaches 0 before <c> is found.
  935.  
  936. char *memchr(char *buf, char c, int cnt)
  937.  Search the first <cnt> bytes of <buf> for <c>.  Returns a pointer to
  938.  the matching character, or NULL if not found.
  939.  
  940. char *bzero(char *buf, int cnt)
  941.  Zero out <cnt> characters in <buf>.  
  942.  Returns <buf>.
  943.  
  944. int strlen(char *string)
  945.  Returns the number of characters in a string, not including the
  946.  terminating '\0'.
  947.  
  948. char *strcpy(char *dest, char *source)
  949.  Copies the <source> string to the <dest> including the '\0'.  A
  950.  pointer to the start of <dest> is returned.
  951.  
  952. char *strncpy(char *dest, char *source, int limit)
  953.  Copies the <source> string to the <dest>.  At most, <limit>
  954.  characters are copied.  If <source> ends before <limit> characters
  955.  have been copied, the '\0' is copied, otherwise <dest> is not
  956.  terminated by the copy.
  957.  
  958. char *strpcpy(char *dest, char *start, char *stop)
  959.  Copies characters from <start> up to <stop> into <dest>.  The
  960.  character pointed to by <stop> is not copied, and MUST be in the
  961.  same string as <start>.  The <dest> pointer is returned.
  962.  
  963. char *strdup(char *string)
  964.  Create a copy of <string> and return a pointer to the copy.
  965.  Storage for the copy is obtained from 'malloc()' and can be 
  966.  freed  with a call to 'free(string)'.
  967.  
  968. char *strset(char *string, char c)
  969.  Fill <string> with <c> upto the terminating '\0' of <string>.
  970.  
  971. char *strnset(char *string, char c, int n)
  972.  Fill at most <n> characters of <string> with <c>, upto the
  973.  terminating '\0' of <string>.
  974.  
  975. char *substr(char *dest, char *source, int start, int end)
  976.  Copy characters from <source> to <dest> starting with character
  977.  <start> and ending with <end>.  A pointer to <dest>, which will
  978.  be '\0' terminated, is returned.
  979.  
  980. char *subnstr(char *dest, char *source, int start, int length)
  981.  Copy <length> characters from <source> to <dest> starting with
  982.  character <start>.  A pointer to <dest>, which will be '\0'
  983.  terminated, is returned.
  984.  
  985. char *strcat(char *dest, char *source)
  986.  Concatenate <source> on the end of <dest>.  The terminator of
  987.  <dest> will be overwritten by the first character of <source>.
  988.  The termintor from <source> will be copied.  A pointer to
  989.  the modified <dest> is returned.
  990.  
  991. char *strncat(char *dest, char *source, int limit)
  992.  Concatenate <limit> characters from <source> onto <dest>.  If
  993.  <source> contains less than <limit> characters, the length of
  994.  source is used for <limit>.  The terminating '\0' is always
  995.  added.  A pointer to <dest> is returned.
  996.  
  997. char *strupr(char *string)
  998.  Convert all alphabetic characters in <string> to upper case.
  999.  
  1000. char *strlwr(char *string)
  1001.  Convert all alphabetic characters in <string> to lower case.
  1002.  
  1003. char *strrev(char *string)
  1004.  Reverse the order of the characters in <string>.
  1005.  
  1006. int strcmp(char *str1, char *str2)
  1007.  Lexicographically compare the two strings.  Return a value
  1008.  indicating the relationship between the strings.  Possible
  1009.  return values are:
  1010.                      negative = str1 < str2
  1011.                      0        = str1 == str2
  1012.                      positive = str1 > str2
  1013.  
  1014. int strncmp(char *str1, char *str2, int limit)
  1015.  Compare strings as with strcmp(), but limit comparison to the
  1016.  <limit> characters.
  1017.  
  1018. int stricmp(char *str1, char *str2)
  1019.  Compare strings as with strcmp(), but ignore the case of any
  1020.  alphabetic characters.
  1021.  
  1022. int strnicmp(char *str1, char *str2, int limit)
  1023.  Compare strings as with strncmp(), but ignore the case of any
  1024.  alphabetic characters.
  1025.  
  1026. char *strstr(char *string, char *pattern)
  1027.  Return a pointer to the first occurance of <pattern> in <string>.
  1028.  NULL is returned if <pattern> is not found.
  1029.  
  1030. char *stristr(char *string, char *pattern)
  1031.  Same as strstr(), but ignore the case of any alphabetic characters.
  1032.  
  1033. char *strchr(char *string, char symbol)
  1034.  Return a pointer to the first occurance of <symbol> in <string>.
  1035.  NULL is returned if <symbol> is not found.  '\0' is included in
  1036.  the search.
  1037.  
  1038. char *strrchr(char *string, char symbol)
  1039.  Return a pointer to the last occurance of <symbol> in <string>.
  1040.  NULL is returned if <symbol> is not found.  '\0' is included in
  1041.  the search.
  1042.  
  1043. int strpos(char *string, char symbol)
  1044.  Return the index of the first occurance of <symbol> in <string>.
  1045.  -1 is returned if <symbol> is not found.
  1046.  
  1047. int strrpos(char *string, char symbol)
  1048.  Return the index of the last occurance of <symbol> in <string>.
  1049.  -1 is returned if <symbol> is not found.
  1050.  
  1051. int strspn(char *string, char *set)
  1052.  Return the length of the sub-string of <string> that consists
  1053.  entirely of characters found in <set>.  The terminating '\0'
  1054.  in <set> is not considered part of the match set.  If the first
  1055.  character of <string> is not in <set>, 0 is returned.
  1056.  
  1057. int strcspn(char *string, char *set)
  1058.  Return the length of the sub-string of <string> that consists
  1059.  entirely of characters 'not' found in <set>.  The terminating '\0'
  1060.  in <set> is not considered part of the match set.  If the first
  1061.  character of <string> is in <set>, 0 is returned.
  1062.  
  1063. char *strpbrk(char *string, char *set)
  1064.  Return a pointer to the first occurance in <string> of any
  1065.  character in <set>.
  1066.  
  1067. char *strrpbrk(char *string, char *set)
  1068.  Return a pointer to the last occurance in <string> of any
  1069.  character in <set>.
  1070.  
  1071. char *strtok(char *string, char *delim)
  1072.  Return a token from <string>.  If <string> is not NULL, it is
  1073.  the beginning of a string from which tokens are to be extracted.
  1074.  Characters found in <delim> are skipped over to find the start
  1075.  of a token, characters are then accumulated until a character in
  1076.  <delim> is found, or the terminator of <string> is reached.
  1077.  A pointer to the '\0' terminated token is then returned.  Note
  1078.  that this function modifies <string> (by inserting '\0's) in
  1079.  the process.  Subsequent calls to strtok() may specify NULL as
  1080.  the <string> argument, in which case subsequent tokens are
  1081.  returned, or NULL if there are no more tokens.
  1082.  
  1083. char *strtrim(char *string, char *junk)
  1084.  Remove leading and trailing characters found in <junk> from
  1085.  <string>.  Return a pointer to the modified <string>.
  1086.  
  1087. char *stradj(char *string, int dir)
  1088.  Adjust <string> by adding space if <dir> is positive, or removing
  1089.  space if <dir> is negative.  The magnitude of <dir> is the number
  1090.  of character positions to add or remove.  Characters are added or
  1091.  removed at the beginning of <string>.  A pointer to the modified
  1092.  <string> is returned.
  1093.  
  1094. int strrpl(char *string, char *ptrn, char *rpl, int n)
  1095.  Replace at most <n> occurances of <ptrn> in <string> with <rpl>.
  1096.  If <n> is -1, replace all.  Return the number of replacments.
  1097.  
  1098. int strirpl(char *string, char *ptrn, char *rpl, int n)
  1099.  Same as strrpl() except ignore the case of alphabetic characters.
  1100.  
  1101. ***********************************************************************
  1102. *                 CHARACTER FUNCTIONS: (misc.lib)                     *
  1103. ***********************************************************************
  1104.  
  1105.  You must include <ctype.h> in your program if you use functions
  1106.  from this section. Please note that the isxxxx() functions,
  1107.  except isascii(), only have defined results if isascii() is true.
  1108.  (ie. they only work properly on values 0x00 through 0x7F)
  1109.  
  1110. int toupper(int c)
  1111.  Convert <c> to upper case, if alphabetic.  This is implemeted
  1112.  as a macro and also as a function.  You may force use of the
  1113.  function version rather than the macro (which evaluates its
  1114.  argument twice) by using the "#undef toupper" directive.
  1115.  
  1116. int tolower(int c)
  1117.  Convert <c> to lower case, if alphabetic.  This is implemeted
  1118.  as a macro and also as a function.  You may force use of the
  1119.  function version rather than the macro (which evaluates its
  1120.  argument twice) by using the "#undef tolower" directive.
  1121.  
  1122. MACRO _toupper(int c)
  1123.  This macro should be used only if <c> is known to be lower case.
  1124.  It converts <c> to upper case.  Results are undefined if converting
  1125.  a character which is not lower case.
  1126.  
  1127. MACRO _tolower(int c)
  1128.  This macro should be used only if <c> is known to be upper case.
  1129.  It converts <c> to lower case.  Results are undefined if converting
  1130.  a character which is not upper case.
  1131.  
  1132. MACRO toascii(int c)
  1133.  Convert <c> to 7-bit ascii, putting it into the range 0x00..0x7F.
  1134.  
  1135. MACRO isalnum(int c)
  1136.  Return non-zero if <c> is '0'..'9','A'..'Z','a'..'z'.
  1137.  
  1138. MACRO isalpha(int c)
  1139.  Return non-zero if <c> is 'A'..'Z','a'..'z'.
  1140.  
  1141. MACRO isascii(int c)
  1142.  Return non-zero if <c> is 0x00..0x7F.
  1143.  
  1144. MACRO iscntrl(int c)
  1145.  Return non-zero if <c> is 0x00..0x1F,0x7F.
  1146.  
  1147. MACRO isdigit(int c)
  1148.  Return non-zero if <c> is '0'..'9'.
  1149.  
  1150. MACRO isgraph(int c)
  1151.  Return non-zero if <c> is 0x21..0x7E.
  1152.  
  1153. MACRO islower(int c)
  1154.  Return non-zero if <c> is 'a'..'z'.
  1155.  
  1156. MACRO isprint(int c)
  1157.  Return non-zero if <c> is 0x20..0x7E.
  1158.  
  1159. MACRO ispunct(int c)
  1160.  Return non-zero if <c> is not iscntrl(), isalnum() or isspace().
  1161.  
  1162. MACRO isspace(int c)
  1163.  Return non-zero if <c> is 0x09..0x0D,0x20.
  1164.  
  1165. MACRO isupper(int c)
  1166.  Return non-zero if <c> is 'A'..'Z'.
  1167.  
  1168. MACRO isxdigit(int c)
  1169.  Return non-zero if <c> is '0'..'9','A'..'F','a'..'f'.
  1170.  
  1171. ***********************************************************************
  1172. *                DATE & TIME FUNCTIONS: (misc.lib)                    *
  1173. ***********************************************************************
  1174.  
  1175.  You should include <time.h> in your program if you use functions
  1176.  from this section.(prototypes/defines)
  1177.  
  1178. time_t time(time_t *rawtime)
  1179.  Get the current system clock date/time value.  Although the value
  1180.  of this function is compatible with the ANSI proposed standard,
  1181.  on some systems (notably System V), this function returns the
  1182.  number of seconds elapsed since 00:00:00 GMT on Jan 1, 1970.
  1183.  This implementation returns an encoded date/time value instead.
  1184.  Therefore any programs which depend on this value being a number
  1185.  of seconds will not work properly.  However, other functions in
  1186.  this section which make use of the raw time value returned by
  1187.  time() are implemented to be compatible with this encoding, and
  1188.  will work properly.  In addition to returning the raw time value,
  1189.  if the <rawtime> pointer is not NULL, the value is stored in
  1190.  the time_t variable <rawtime> points to.
  1191.  
  1192. char *ctime(time_t *rawtime)
  1193.  Convert <rawtime> to a string.  A 26 character fixed field string
  1194.  is created from the raw time value.  The following is an example
  1195.  of what this string might look like:
  1196.                                       "Wed Jul 08 18:43:07 1987\n\0"
  1197.  
  1198.  A pointer to the formatted string, which is held in an internal buffer, 
  1199.  is returned.
  1200.  
  1201. struct tm *localtime(time_t *rawtime)
  1202.  Convert <rawtime> to fill time structure fields.  A pointer to an
  1203.  internal structure is returned.  Refer to <time.h> for the values
  1204.  of the various structure fields.
  1205.  
  1206. struct tm *gmtime(time_t *rawtime)
  1207.  This function currently returns NULL, as specified by the 
  1208.  ANSI standard.
  1209.  
  1210. char *asctime(struct tm *time)
  1211.  Convert <time> structure value to a string.  The same format, and
  1212.  the same internal buffer, as for ctime() is used for this function.
  1213.  
  1214. ***********************************************************************
  1215. *            SEARCHING & SORTING: (misc.lib/string.lib)               *
  1216. ***********************************************************************
  1217.  
  1218.  You should include <stdlib.h> or <string.h> in your program if you 
  1219.  use functions from this section.(prototypes).
  1220.  I have placed a comment at the end of each function description to
  1221.  explain which include is needed.
  1222.  
  1223. void qsort(char *base, int num, int size, int (*cmp)())
  1224.  Perform a recursive quick-sort on an array starting at <base>
  1225.  containing <num> elements of <size> bytes each.  The function
  1226.  pointed to by <cmp> is used to compare elements.  Pointers to
  1227.  two items in the array are passed to the function, which must
  1228.  return a number representing their relationship as follows:
  1229.  
  1230.           negative  =  item1 < item2
  1231.           0         =  item1 == item2
  1232.           positive  =  item1 > item2
  1233.  
  1234.  The qsort() function requires the use of a temporary data area
  1235.  that is large enough to hold <size> bytes.  The default space
  1236.  provided is 128 bytes large.  If your record size is larger than
  1237.  128 bytes, YOU MUST provide an alternative storage area.  The
  1238.  global variable "_qbuf" points to the storage qsort() will use.
  1239.  Setting "_qbuf" to NULL restores use of the internal buffer.
  1240.  This routine is optimized to avoid N*N sort times for ordered data.
  1241.  In fact, performance on sorted or reverse-sorted data is actually
  1242.  "best case" with this algorithm, rather than "worst case" as with
  1243.  most qsort() implementations. (include: <stdlib.h>)
  1244.  
  1245. void hsort(char *base, int num, int size, int (*cmp)())
  1246.  Perform an N*log(N) heap-sort on an array starting at <base>
  1247.  containing <num> elements of <size> bytes each.  The function
  1248.  pointed to by <cmp> is used to compare elements.  Pointers to
  1249.  two items in the array are passed to the function, which must
  1250.  return a number representing their relationship as follows:
  1251.  
  1252.           negative  =  item1 < item2
  1253.           0         =  item1 == item2
  1254.           positive  =  item1 > item2
  1255.  
  1256.  The hsort() function requires no extra storage, is not recursive,
  1257.  and has an almost constant N*log(N) sort time.  In the average
  1258.  case, it is about half as fast as qsort() on random data.  If
  1259.  portability is a concern, it should be noted that qsort() is
  1260.  almost always available, but hsort() is not. (include: <stdlib.h>)
  1261.  
  1262. char *bsearch(char *key, char *base, int num, int size, int (*cmp)())
  1263.  Perform a binary search for <key> on the sorted data at <base>.
  1264.  <num>, <size> and <cmp> are like the corresponding parameters
  1265.  to qsort().  A pointer to the matching element is returned for
  1266.  success, or NULL for failure.  The global variable "_bsearch"
  1267.  will contain the index of either the matching element, or the
  1268.  index of the element that the <key> value should be inserted
  1269.  after.  The use of "_bsearch" is not supported by most
  1270.  implementations of bsearch(). (include: <string.h>)
  1271.  
  1272. char *lsearch(char *key, char *base, int *num, int size, int (*cmp)())
  1273.  Perform a linear search for <key> on the data at <base>. The
  1274.  <num>, <size> and <cmp> parameters are like the corresponding
  1275.  parameters to qsort().  A pointer to the first matching element
  1276.  is returned for success, or NULL for failure.  If <key> is not
  1277.  found, it will be added to the end of the array and <num> will
  1278.  be incremented.  Note that, unlike bsearch() and qsort(), the
  1279.  <num> parameter is a POINTER to a location which holds the
  1280.  number of elements to sort. (include: <stdlib.h>)
  1281.  
  1282. char *lfind(char *key, char *base, int *num, int size, int (*cmp)())
  1283.  Like lsearch(), but do not add elements which are not found.
  1284.  Note that <num> is a POINTER, even though it is not modified.
  1285.  (include: <stdlib.h>)
  1286.  
  1287. ***********************************************************************
  1288. *             ERROR HANDLING FUNCTIONS: (misc.lib)                    *
  1289. ***********************************************************************
  1290.  
  1291.  You should include <stdlib.h> in your program if you use functions
  1292.  from this section.(prototypes/defines)
  1293.  
  1294. int errno;
  1295.  This variable is set to zero when the program is loaded.  It is
  1296.  not zeroed out by any library functions, but may be set to a 
  1297.  non-zero error number by many of them (particularly the 
  1298.  standard i/o and system service functions).  The meaning of 
  1299.  this error number may be found in the symbolic #defines in <errno.h>.
  1300.  
  1301. void perror(char *msg)
  1302.  Write, to stderr, <msg> (if non-null and non-empty), followed by
  1303.  ": " and a system error message derived from the value of errno.
  1304.  
  1305. char *strerror(int errnum)
  1306.  Return the system error message for error <errnum>.  If <errnum>
  1307.  is outside the range of valid error numbers, NULL is returned.
  1308.  
  1309. ***********************************************************************
  1310. *                   VARIABLE ARGUMENT LISTS:                          *
  1311. ***********************************************************************
  1312.  
  1313.  You must include <stdarg.h> in your program if you use functions
  1314.  from this section. (macros)
  1315.  
  1316. typedef ... va_list;
  1317.  This is the type for a variable argument list traversal variable.
  1318.  
  1319. MACRO va_start(list, param)
  1320.  This macro initializes the va_list variable <list> to begin
  1321.  traversing variable argument lists.  <param> is the last parameter
  1322.  in the function call before the variable arguments began.  This
  1323.  parameter MUST NOT be a register variable.
  1324.  
  1325. MACRO va_arg(list, type)
  1326.  This macro retrieves a variable argument of type <type>, updates
  1327.  the va_list variable <list>, and returns the value of the retrieved
  1328.  argument.  The <type> should not be parenthesised.
  1329.  
  1330. MACRO va_end(list)
  1331.  This macro must be called after all desired variable arguments have
  1332.  been retrieved, to reset the context of the va_list variable <list>.
  1333.  
  1334. ***********************************************************************
  1335. *             MISCELLANEOUS FUNCTIONS: (misc.lib/string.lib)          *
  1336. ***********************************************************************
  1337.  
  1338.  You should include <stdlib.h>, <string.h>, <macros.h> or <assert.h> in
  1339.  your program if you use functions from this section.(prtypes/defs/macros).
  1340.  I have placed a comment at the end of each function description to
  1341.  explain which include is needed.
  1342.  
  1343. int getopt(int argc, char **argv, char *optstring)
  1344.  This function eases the processing of the command line.  Each call
  1345.  returns a character from <optstring>, with optarg set to a parameter
  1346.  if one is required; or a '?' indicating that an invalid option was
  1347.  found; or EOF indicating that all options have been processed.  The
  1348.  <argc> and <argv> parameters are (of course) the argc and argv values
  1349.  passed to main().  The <opstring> is a string of option characters.
  1350.  If an option takes a parameter, it is followed by a ':' in <optstring>,
  1351.  and the char *optarg variable (global) will be set to point to the
  1352.  parameter string from the command line.  For example, "bno:v" defines
  1353.  the valid option characters as 'b', 'n', 'o' and 'v', and 'o' takes
  1354.  a parameter.  All options must be preceeded (in the command line) by
  1355.  a '-' character.  A single '-' character is taken to indicate stdin
  1356.  as a file, and terminates the argument processing.  A "--" string
  1357.  indicated the end of options, and is skipped over.  When option
  1358.  processing is successfully completed, the global variable optind will
  1359.  contain the index into argv[] of the next argument to be processed.
  1360.  Subsequent arguments should be processed with a loop like this:
  1361.  
  1362.          while(optind < argc)
  1363.                process(argv[optind++]);
  1364.  
  1365.  If an error occurs during argument process, an error message is
  1366.  written to stderr and '?' is returned by getopt().  Your program
  1367.  should then give a usage message and abort.  If the global variable
  1368.  opterr is set to zero, no error message will be given, but '?' will
  1369.  still be returned.  Note that command lines accepted by getopt() are
  1370.  quite flexible.  The command lines "-b -v -o filename -- - file",
  1371.  "-vbofilename - file",  and "-ofilename -bv - file" all will return
  1372.  the 'b', 'v', and 'o' options with the parameter to 'o' set to
  1373.  "filename" and leave the arguments "-" and "file2" for further
  1374.  processing. (include: <stdlib.h>)
  1375.  
  1376. int rand()
  1377.  Return a pseudorandom number in the range of 0..32767.
  1378.  (include: <stdlib.h>)
  1379.  
  1380. void srand(unsigned int seed)
  1381.  Seed the random number generator. Default seed is 1.
  1382.  (include: <stdlib.h>)
  1383.  
  1384. void swab(int *src, int *dst, int n)
  1385.  Swap adjacent bytes while copying <n> bytes from <src> to <dst>.
  1386.  This allows bulk translation to/from Intel byte ordering.  Please
  1387.  note the backward order of the <src> and <dst> parameters.
  1388.  (include: <string.h>)
  1389.  
  1390. MACRO abs(x)
  1391.  Return the absolute value of <x>.  This macro evalutes it's
  1392.  argument twice. ((x)<0?(-(x)):(x))
  1393.  (include: <macros.h>)
  1394.  
  1395. MACRO max(x,y)
  1396.  Return the larger of <x> and <y>.  This macro evaluates the
  1397.  larger argument twice and the smaller argument once.
  1398.  (include: <macros.h>)
  1399.  
  1400. MACRO min(x,y)
  1401.  Return the smaller of <x> and <y>.  This macro evaluates the
  1402.  smaller argument twice and the larger argument once.
  1403.  (include: <macros.h>)
  1404.  
  1405. MACRO swap(a,b)
  1406.  Exchange <a> and <b> by chained XORs.  The macro evaluates
  1407.  each argument several times.
  1408.  (include: <macros.h>)
  1409.  
  1410. MACRO assert(condition)
  1411.  If <condition> is not true at run-time, this macro causes an
  1412.  assert failure message to be written to stderr, displaying the
  1413.  line number and source file name, and aborts the program.  If the
  1414.  symbol NDEBUG is #defined, all assert() calls are disabled.
  1415.  (include: <assert.h>)
  1416.  
  1417.  
  1418. ----- REVISION RECORD -----
  1419.  
  1420. This area will contain a rough record of the changes I have made to 'dlibs'
  1421. for future releases of HCE.
  1422.  
  1423. Amiga V1.0
  1424.  Original release. 21/6/94.
  1425.  
  1426.  
  1427. ----- FINAL NOTE -----
  1428.  
  1429. If you think that this document is difficult to understand or that
  1430. this version of 'dlibs' is missing things you need, or you have found
  1431. a bug or bugs, then please write to:
  1432.  
  1433. Jason Petty
  1434. 32 Balder Road,
  1435. Norton,
  1436. Stockton-On-Tees,
  1437. Cleveland. TS20 1BE.
  1438.  
  1439. all comments welcome, but please note I cannot reply to all letters!.
  1440.  
  1441. ----- END OF FILE -----
  1442.